<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>ps</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_1802">&nbsp;</a>NAME</h4><blockquote>
ps - report process status
</blockquote><h4><a name = "tag_001_014_1803">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

ps <b>[</b>-aA<b>][</b>-defl<b>][</b>-G <i>grouplist</i><b>][</b>-o <i>format</i><b>]</b>...<b>[</b>-p <i>proclist</i><b>][</b>-t <i>termlist</i><b>]
[</b>-U <i>userlist</i><b>][</b>-g <i>grouplist</i><b>][</b>-n <i>namelist</i><b>][</b>-u <i>userlist</i><b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_1804">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>ps</i>
utility writes information about processes, subject to having
the appropriate privileges to obtain information about those processes.
<p>
By default,
<i>ps</i>
selects all processes with the same effective user ID
as the current user and the same controlling terminal as the invoker.
</blockquote><h4><a name = "tag_001_014_1805">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>ps</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> .
<p>
The following options are supported:
<dl compact>

<dt><b>-a</b>
<dd>Write information for all processes associated with terminals.
Implementations may omit session leaders from this list.

<dt><b>-A</b>
<dd>Write information for all processes.

<dt><b>-d</b>
<dd>Write information for all processes, except session leaders.

<dt><b>-e</b>
<dd>Write information for all processes
(equivalent to
<b>-A</b>).

<dt><b>-f</b>
<dd>Generate a
<i>full</i>
listing.
(See the STDOUT section for the contents of a full listing.)

<dt><b>-g&nbsp;</b><i>grouplist</i>
<dd>
Write information for processes whose session leaders are given in
<i>grouplist</i>.
The
<i>grouplist</i>
must be a single argument in the form of
a
blank-
or comma-separated list.

<dt><b>-G&nbsp;</b><i>grouplist</i>
<dd>
Write information for processes whose real group ID numbers are given in
<i>grouplist</i>.
The
<i>grouplist</i>
must be a single argument in the form of
a
blank-
or comma-separated list.

<dt><b>-l</b>
<dd>Generate a
<i>long</i>
listing.
(See the STDOUT section for the contents of a long listing.)

<dt><b>-n&nbsp;</b><i>namelist</i>
<dd>
Specify the name of an alternative system
<i>namelist</i>
file in place of the default.
The name of the default file and the format of a
<i>namelist</i>
file are unspecified.

<dt><b>-o&nbsp;</b><i>format</i>
<dd>
Write information according to the format specification given in
<i>format</i>.
This is fully described in the STDOUT section.
Multiple
<b>-o</b>
options can be specified; the format specification will be interpreted
as the
space-character-separated
concatenation of all the
<i>format</i>
option-arguments.

<dt><b>-p&nbsp;</b><i>proclist</i>
<dd>
Write information for processes whose process ID numbers are given in
<i>proclist</i>.
The
<i>proclist</i>
must be a single argument in the form of
a
blank-
or comma-separated list.

<dt><b>-t&nbsp;</b><i>termlist</i>
<dd>
Write information for processes associated with terminals given in
<i>termlist</i>.
The
<i>termlist</i>
must be a single argument in the form of
a
blank-
or comma-separated list.
Terminal identifiers must be given
in one of two forms:
the device's filename (for example,
<b>tty04</b>)
or, if the device's filename starts with
<b>tty</b>,
just the
identifier following the characters
<b>tty</b>
(for example,
<b>04</b>).

<dt><b>-u&nbsp;</b><i>userlist</i>
<dd>
Write information for processes whose user ID numbers or
login names are given in
<i>userlist</i>.
The
<i>userlist</i>
must be a single argument in the form of
a
blank-
or comma-separated list.
In the listing, the numerical user ID
will be written unless the
<b>-f</b>
option is used, in which case
the login name will be written.

<dt><b>-U&nbsp;</b><i>userlist</i>
<dd>
Write information for processes whose real user ID numbers or
login names are given in
<i>userlist</i>.
The
<i>userlist</i>
must be a single argument in the form of
a
blank-
or comma-separated list.

</dl>
<p>
With the exception of
<b>-o</b>&nbsp;<i>format</i>,
all of the options shown are used to select processes.
If any are specified, the default list will be ignored and
<i>ps</i>
will select
the processes represented by the inclusive OR
of all the selection-criteria options.
</blockquote><h4><a name = "tag_001_014_1806">&nbsp;</a>OPERANDS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1807">&nbsp;</a>STDIN</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_1808">&nbsp;</a>INPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1809">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>ps</i>:
<dl compact>

<dt><i>COLUMNS</i><dd>
Override the system-selected horizontal screen size,
used to determine the number of text columns to display.
See
the <b>XBD</b> specification, <a href="../xbd/envvar.html"><b>Environment Variables</b>&nbsp;</a> 
for valid values and results when it is unset or null.

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error
and informative messages written to standard output.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
<dt><i>LC_TIME</i><dd>
Determine the
format and contents of the date and time strings displayed.

</dl>
</blockquote><h4><a name = "tag_001_014_1810">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1811">&nbsp;</a>STDOUT</h4><blockquote>
When the
<b>-o</b>
option is not specified, the standard output format is
as follows.
The column headings and
descriptions of the columns in a
<i>ps</i>
listing are given below.
The precise meanings of these fields are implementation-dependent.
The letters
<b>f</b>
and
<b>l</b>
(below) indicate the option (<b> full</b>
or
<b>long</b>)
that causes the corresponding heading to appear;
<b>all</b>
means that the heading always appears.
Note that these two options determine
only what information is provided for a process; they do
not determine which processes will be listed.
<pre>
<table  align=center><tr valign=top><th align=left>F
<th align=left>(l)
<th align=center> Flags (octal and additive) associated with the process. 
<tr valign=top><td align=left>S
<td align=left>(l)
<td align=center>The state of the process.
<tr valign=top><td align=left>UID
<td align=left>(f,l)
<td align=center> The user ID number of the process owner; the login name is printed under the <b>-f</b> option. 
<tr valign=top><td align=left>PID
<td align=left>(all)
<td align=center> The process ID of the process; it is possible to kill a process if this datum is known. 
<tr valign=top><td align=left>PPID
<td align=left>(f,l)
<td align=center>The process ID of the parent process.
<tr valign=top><td align=left>C
<td align=left>(f,l)
<td align=center>Processor utilisation for scheduling.
<tr valign=top><td align=left>PRI
<td align=left>(l)
<td align=center> The priority of the process; higher numbers mean lower priority. 
<tr valign=top><td align=left>NI
<td align=left>(l)
<td align=center> Nice value; used in priority computation. 
<tr valign=top><td align=left>ADDR
<td align=left>(l)
<td align=center>The address of the process.
<tr valign=top><td align=left>SZ
<td align=left>(l)
<td align=center> The size in blocks of the core image of the process. 
<tr valign=top><td align=left>WCHAN
<td align=left>(l)
<td align=center> The event for which the process is waiting or sleeping; if blank, the process is running. 
<tr valign=top><td align=left>STIME
<td align=left>(f)
<td align=center>Starting time of the process.
<tr valign=top><td align=left>TTY
<td align=left>(all)
<td align=center>The controlling terminal for the process.
<tr valign=top><td align=left>TIME
<td align=left>(all)
<td align=center> The cumulative execution time for the process. 
<tr valign=top><td align=left>CMD
<td align=left>(all)
<td align=center> The command name; the full command name and its arguments are written under the <b>-f</b> option. 
</table>
</pre>
<p>
A process that has exited and has a parent, but has not
yet been waited for by the parent, is marked
<b>defunct</b>.
<p>
Under the option
<b>-f</b>,
<i>ps</i>
tries to determine the command name
and arguments given when the process was created
by examining memory or the swap area.
Failing this, the command name, as it
would appear without the option
<b>-f</b>,
is written in square brackets.
<p>
The
<b>-o</b>
option allows the output format to be
specified under user control.
<p>
The format specification must be a list of names
presented as a single argument,
blank-
or comma-separated.
Each variable has a default header.
The default header can be overridden
by appending an equals sign and the new
text of the header.
The rest of the characters in the argument
will be used as the header text.
The fields specified will be written in the order specified
on the command line, and should be arranged in columns in the output.
The field widths will be selected by the system to be at least
as wide as the header text (default or overridden value).
If the header text is null, such as
<b>-o</b>
user=,
the field width will be at least as wide as the
default header text.
If all header text fields are null,
no header line will be written.
<p>
The following names are recognised in the POSIX locale:
<dl compact>

<dt><b>ruser</b><dd>The real user ID of the process.
This will be the textual user ID,
if it can be obtained and the field width permits,
or a decimal representation otherwise.

<dt><b>user</b><dd>The effective user ID of the process.
This will be the textual user ID,
if it can be obtained and the field width permits,
or a decimal representation otherwise.

<dt><b>rgroup</b><dd>The real group ID of the process.
This will be the textual group ID,
if it can be obtained and the field width permits,
or a decimal representation otherwise.

<dt><b>group</b><dd>The effective group ID of the process.
This will be the textual group ID,
if it can be obtained and the field width permits,
or a decimal representation otherwise.

<dt><b>pid</b><dd>The decimal value of the process ID.

<dt><b>ppid</b><dd>The decimal value of the parent process ID.

<dt><b>pgid</b><dd>The decimal value of the process group ID.

<dt><b>pcpu</b><dd>The ratio of CPU time used recently
to CPU time available in the same period, expressed as a percentage.
The meaning of &quot;recently&quot; in this context is unspecified.
The CPU time available is determined in an unspecified manner.

<dt><b>vsz</b><dd>The size of the process in (virtual) memory in kilobytes as a decimal integer.

<dt><b>nice</b><dd>The decimal value of the system scheduling priority of the process.
See
<i><a href="nice.html">nice</a></i>.

<dt><b>etime</b><dd>In the POSIX locale, the elapsed time since the process
was started, in the form:
<pre>
<code>
<b>[[</b><i>dd</i>-<b>]</b><i>hh</i>:<b>]</b><i>mm</i>:<i>ss
</i></code>
</pre>
where
<i>dd</i>
will represent the number of days,
<i>hh</i>
the number of hours,
<i>mm</i>
the number of minutes, and
<i>ss</i>
the number of seconds.
The
<i>dd</i>
field will be a decimal integer.
The
<i>hh</i>,
<i>mm</i>
and
<i>ss</i>
fields will be two-digit decimal integers padded on the left with zeros.

<dt><b>time</b><dd>In the POSIX locale, the cumulative CPU time of the process in the form:
<pre>
<code>
<b>[</b><i>dd</i>-<b>]</b><i>hh</i>:<i>mm</i>:<i>ss
</i></code>
</pre>

The
<i>dd</i>,
<i>hh</i>,
<i>mm</i>
and
<i>ss</i>
fields will be as described in the
<b>etime</b>
specifier.

<dt><b>tty</b><dd>The name of the controlling terminal of the process
(if any) in the same format used by the
<i><a href="who.html">who</a></i>
utility.

<dt><b>comm</b><dd>The name of the command being executed
(<i>argv</i>[0]
value) as a string.

<dt><b>args</b><dd>The command with all its arguments as a string.
The implementation may truncate this value to the field width;
it is implementation-dependent whether any further truncation occurs.
It is unspecified whether the string represented is a
version of the argument list as it was
passed to the command when it started, or is a
version of the arguments as they may
have been modified by the application.
Applications cannot depend on being able to
modify their argument list and having
that modification be reflected in the output of
<i>ps</i>.

</dl>
<p>
Any field need not be meaningful in all implementations.
In such a case a hyphen
(-)
should be output in place of the field value.
<p>
Only
<b>comm</b>
and
<b>args</b>
are allowed to contain
blank characters;
all others are not.
Any implementation-dependent variables will be specified in the
system documentation
along with the default header
and indicating if the field may contain
blank characters.
<p>
The following table
specifies the default header to be used in the POSIX locale
corresponding to each format specifier.
<pre>
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Format Specifier</b>
<th align=center><b>Default Header</b>
<th align=center><b>Format Specifier</b>
<th align=center><b>Default Header</b>
<tr valign=top><td align=left>args
<td align=left>COMMAND
<td align=left>ppid
<td align=left>PPID
<tr valign=top><td align=left>comm
<td align=left>COMMAND
<td align=left>rgroup
<td align=left>RGROUP
<tr valign=top><td align=left>etime
<td align=left>ELAPSED
<td align=left>ruser
<td align=left>RUSER
<tr valign=top><td align=left>group
<td align=left>GROUP
<td align=left>time
<td align=left>TIME
<tr valign=top><td align=left>nice
<td align=left>NI
<td align=left>tty
<td align=left>TT
<tr valign=top><td align=left>pcpu
<td align=left>%CPU
<td align=left>user
<td align=left>USER
<tr valign=top><td align=left>pgid
<td align=left>PGID
<td align=left>vsz
<td align=left>VSZ
<tr valign=top><td align=left>pid
<td align=left>PID
<td align=left>&nbsp;
<td align=left>&nbsp;
</table>
</pre>
<h6 align=center><xref table="Variable Names and Default Headers in <I>ps</i>"></xref>Table: Variable Names and Default Headers in <i>ps</i></h6>
</blockquote><h4><a name = "tag_001_014_1812">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_1813">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1814">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1815">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>Successful completion.

<dt>&gt;0<dd>An error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_1816">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1817">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
Things can change while
<i>ps</i>
is running; the snapshot it gives is only true for an instant,
and might not be accurate by the time it is displayed.
<p>
The
<b>args</b>
format specifier is allowed to produce a truncated
version of the command arguments.
In some implementations, this information
is no longer available when the
<i>ps</i>
utility is executed.
<p>
If the field width is too narrow to display a textual ID,
the system may use a numeric version.
Normally, the system would be expected to choose large
enough field widths, but if a large number of fields
were selected to write, it might squeeze fields
to their minimum sizes to fit on one line.
One way to ensure adequate width for the textual IDs
is to override the
default header for a field to make it larger than
most or all user or group names.
<p>
There is no special quoting mechanism for header text.
The header text is the rest of the argument.
If multiple header changes are needed,
multiple
<b>-o</b>
options can be used, such as:
<pre>
<code>
ps -o "user=User Name" -o pid=Process\ ID
</code>
</pre>
<p>
On some systems, especially multi-level secure systems,
<i>ps</i>
may be severely restricted and produce information
only about child processes owned by the user.
<br>
</blockquote><h4><a name = "tag_001_014_1818">&nbsp;</a>EXAMPLES</h4><blockquote>
The command:
<pre>
<code>
ps -o user,pid,ppid=MOM -o args
</code>
</pre>
writes at least the following in the POSIX locale:
<pre>
<dl compact><dt> <dd>
<table <tr valign=top><th align=right>USER
<th align=left>PID
<th align=right>MOM
<th align=left>COMMAND
<tr valign=top><td align=right>helene
<td align=left>34
<td align=right>12
<td align=left>ps -o uid,pid,ppid=MOM -o args
</table>
</dl>
</pre>
The contents of the
<b>COMMAND</b>
field need not be the same in all implementations, due
to possible truncation.
</blockquote><h4><a name = "tag_001_014_1819">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1820">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="kill.html">kill</a></i>,
<i><a href="nice.html">nice</a></i>,
<i><a href="renice.html">renice</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
